Skip to content

doc: PWA + push notifications design for #1254 (epic #1184) - #3314

Merged
dezren39 merged 2 commits into
mainfrom
queue/4957-1254-pwa-push-design
Nov 1, 2026
Merged

dezren39 merged 2 commits into
mainfrom
queue/4957-1254-pwa-push-design

Conversation

@dezren39

@dezren39 dezren39 commented Nov 1, 2026 •

Copy link
Copy Markdown
Member

Design deliverable for #1254, per queue task 4957 (triage task 2514, CONFIRMED greenfield at a1aa07d).

The note (doc/2026-11-01T03-54-00Z_design_pwa_push_notifications.md) answers every #1254 design question:

  • Classes/defaults — five classes sourced from existing surfaces (/api/attention.json needs-drew tier, /api/quota.json, /api/health), with quota classes constrained by the standing quota doctrine (routine exhaustion stays silent; sole-door pools are the exception). Defaults are named as Drew's call (Q1) with a recommendation.
  • Quiet hours/batching — 23:00–07:00 America/Chicago default, midday + window-end digests, a two-item breakthrough set.
  • Delivery branched on design(pm-stack): one public URL for the dashboard behind Cloudflare Access (settled access model, not yet implemented) #1182 — Web Push is outbound-only, so branch A (tailnet-only, today) is buildable now; branch B (behind Access) is a config flip + one Access deep-link acceptance check. Subscription store follows the comments/registry JSON pattern.
  • Deep-link contract — every notification lands on the item's triage-capable view, never a generic page; plain-text fallback in the body.
  • Anti-fatigue — (class, ref, fingerprint) dedupe, 6h cooldown, needs-drew escalation ladder (+24h batched, +48h breakthrough, then weekly), acted-on detection from existing stores, weekly sent-vs-acted-on roll-up with default-off proposals only.
  • /sw.js kill-switch disposition — two-step, probe-gated replacement: installability ships first with the kill switch untouched; the real worker replaces it only after 14 days of probe data show no foreign registration, or it carries the eviction job for one release. No release ever serves a /sw.js that neither evicts nor is the real worker.
  • Open questions for Drew — five, explicit, in §8 (defaults, quiet hours/breakthrough, blocked-age cadence, VAPID contact, second device).

Implementation issues are filed separately and attached as sub-issues of epic #1184, linked from #1254. Design only — no code.

Refs #1254, #1184, #1182.


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

…ts, quiet hours, Web Push branched on #1182, deep links, anti-fatigue, /sw.js disposition)
@dezren39
dezren39 requested a review from a team as a code owner November 1, 2026 03:56
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-01T04:04:04.645073Z 76e8983 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 21 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: e8fd7136-8b08-40e4-a958-caaecdc02c65
Commits

Reviewing files that changed from the base of the PR and between 6e7f8fc and 76e8983.

Files selected for processing: 1
  • doc/2026-11-01T03-54-00Z_design_pwa_push_notifications.md
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c59150591b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +143 to +146
**Branch A — tailnet-only (today's reality).** The aggregator binds
`127.0.0.1:4870` + the tailnet name; there is no public route
(#1182 triage, verified at `f00dde689`). Subscriptions are created
from the tailnet origin while the phone is on the tailnet, pushes

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Make trusted HTTPS a prerequisite for branch A

On the current deployment, branch A cannot create the subscriptions described here: pm-stack/aggregator/README.md:38 identifies the canonical origin as http://amd-6.raptor-pumpkinseed.ts.net:4870, and src/server.ts starts plain HTTP listeners. Being connected through Tailscale does not make that remote HTTP origin a browser secure context. The Secure Contexts specification requires a secure context to register service workers, and the Push API likewise restricts PushManager to secure contexts. Add a trusted HTTPS endpoint to branch A's prerequisites and implementation slices; otherwise the recommended path cannot deliver push notifications on Drew's phone, regardless of the outbound-only sending architecture.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 76e8983: branch A now carries the trusted-HTTPS prerequisite — the canonical tailnet origin is plain HTTP (README:38), which is not a secure context, so no SW/PushManager subscription is possible on it. The design now starts branch A by serving the aggregator via Tailscale Serve HTTPS (that origin becomes PM_AGG_PUBLIC_ORIGIN), and slice (a) includes the Serve mapping + docs.


| Class | Source | Trigger | Recommended default |
|---|---|---|---|
| `needs-drew` | `/api/attention.json`; the `needs-drew` tier is derived in `src/derive.ts:308-324` | an item *enters* the needs-drew tier | **on** |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include non-session needs-drew items in the engine's source

When a decision, task, or gap appears in the dashboard's needs-drew queue without a matching session, polling /api/attention.json will never detect it. pm-stack/aggregator/src/server.ts:780-789 returns only view.all plus needs-orchestrator watchdog entries, while src/derive.ts:435-463 keeps these non-session items separately in view.drewExtra; src/render.ts:2402-2410 explicitly includes them in the displayed queue. Consequently, the specified source misses both entry notifications and blocked-age escalation for these actionable items. Have the design consume the complete shared attention view, extend the API, or incorporate the orchestration tier source before defining it as the engine's input.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 76e8983: the engine source is now specified as the complete in-process attention view (view.all + view.drewExtra, derive.ts:379,463 — the non-session decisions/tasks/gaps render.ts:2402 shows), not the flat /api/attention.json array (server.ts:780-789, all+watchdog only). Slice (c) also extends /api/attention.json with the drewExtra entries so external consumers see the same queue.

…for branch A; engine source is the full attention view incl. drewExtra
@dezren39

dezren39 commented Nov 1, 2026

Copy link
Copy Markdown
Member Author

@codex review — both P2 findings addressed in 76e8983 (HTTPS prerequisite for branch A via Tailscale Serve; engine source = full attention view incl. drewExtra + /api/attention.json extension in slice c). Please re-review the new head.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: 76e8983243

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@dezren39
dezren39 merged commit d64e83c into main Nov 1, 2026
1 check passed
@dezren39
dezren39 deleted the queue/4957-1254-pwa-push-design branch November 1, 2026 04:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant